# Device Note - Traffic Light LED Module

## What It Is
A traffic light module is a small PCB with three LEDs (red, yellow, green) and built-in current-limiting resistors. It replicates the layout of a pedestrian or road traffic signal at a scale that fits a breadboard.

## Why It Is Used
Three separately controllable LEDs in a familiar real-world form factor make it easy to introduce sequenced output, state machines, and colour-coded status indicators without wiring individual components.

## Pin Overview
This module uses a 4-pin header:
- `GND` — ground
- `R` — red LED control (active high)
- `Y` — yellow LED control (active high)
- `G` — green LED control (active high)

Connection in this course:
- `R` -> `PB12`
- `Y` -> `PB13`
- `G` -> `PB14`

All three are standard GPIO output pins on the Bluepill.

## Control Behavior
Each pin drives one LED independently. Commands in this course treat them as exclusive states:

| Command | Effect |
|---|---|
| `TRAFFIC_RED_ON` | Red on, yellow off, green off |
| `TRAFFIC_YELLOW_ON` | Yellow on, red off, green off |
| `TRAFFIC_GREEN_ON` | Green on, red off, yellow off |
| `TRAFFIC_ALL_OFF` | All LEDs off |

The current traffic light state streams in the compact USB telemetry frame every 120 ms as `traffic_light` (0 = off, 1 = red, 2 = yellow, 3 = green).

## Wiring Rules
- Resistors are built into the module — do not add external series resistors or the LEDs will be very dim.
- Active high: set the GPIO pin HIGH to turn the LED on.
- All three LEDs share the same `GND` connection on the module.

## Common Failure Modes
- GND not connected — no LEDs light regardless of pin state.
- Pin and LED colour swapped — wrong LED turns on for a given command; check R/Y/G -> PB12/PB13/PB14 mapping.
- Module connected to 5 V GPIO directly — the STM32 PB pins are 5 V tolerant, but running the module from 5 V logic without 3.3 V supply may over-drive the LEDs; keep at 3.3 V.
- All LEDs glow faintly — floating GPIO pin; set the pin as push-pull output, not input.

## Classroom Notes
- The familiar traffic light sequence (red → yellow → green → yellow → red) is an excellent introduction to state machines and time-sequenced automation.
- Challenge students to replicate the UK highway code sequence using the automation tool.
- Ask "why does a real traffic light not just have one wire?" — leads into discussion of independent control lines vs multiplexing.
- The `traffic_light` telemetry value (0–3) is a good example of encoding state as a number.

## Integration With This Course
- Pairs well with Lesson 2 (LEDs & GPIO & Blinking) — first LED control exercise.
- Pairs well with Lesson 3 (Commands, Modes & State) — introducing named commands and state reporting.
- Pairs well with Lesson 10 (Automation Tool & Control Logic) — sequencing traffic light states using automation steps and delays.
- Telemetry key: `traffic_light` (0 = off, 1 = red, 2 = yellow, 3 = green)
- Automation variable token: `{traffic_light}`